// Copyright 2007 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.enterprise.connector.gdata;

import java.util.*;

import com.google.enterprise.connector.spi.DocumentList;
import com.google.enterprise.connector.spi.Document;
import com.google.enterprise.connector.spi.RepositoryException;
import com.google.enterprise.connector.spi.SpiConstants;
import com.google.enterprise.connector.spi.Value;

/**
 * This class is a slight modification of SimpleDocumentList from the SPI.
 * It allows iteration over the list of documents passed to the constructor
 * and additionally stores a checkpoint string to be used after the entire list
 * has been traversed.  The LASTMODIFIED property is used for checkpointing.
 * 
 * In the context of the GData connector, this allows the returning of the last
 * feed fetch time after the final document to be returned instead of simply the
 * last modified time of the last document traversed.  In this way, the updates
 * to the feed can be requested with the last fetch time as the ifModifiedSince
 * parameter instead of a last modification time (which may be much further back
 * in time).
 * 
 * Note: There is nothing actually GData specific about this class other than
 * the name.  It depends only on interfaces from the SPI.
 * 
 * @author amsmith@google.com (Adam Smith)
 *
 */
public class GdDocumentList implements DocumentList {
  List documents;
  Document document;
  String finalCheckpoint;
  Iterator iterator;
  
  /**
   * Build a DocumentList from the given documents and a special finalCheckpoint
   * value.
   * 
   * @param documents a java.util.List of Document implementing objects
   * @param finalCheckpoint a string to be returned when checkpoint is called
   * after all documents in this list have been traversed.
   */
  public GdDocumentList(List documents, String finalCheckpoint) {
    this.documents = documents;
    this.finalCheckpoint = finalCheckpoint;
  }
  
  /** {@inheritDoc} */
  public Document nextDocument() {
    if (iterator == null) {
      iterator = documents.iterator();
    }
    if (iterator.hasNext()) {
      document = (Document) iterator.next();
      return document;
    } else {
      document = null;
      return null;
    }
  }

  /**
   * If the traversal has not yet ended, this method returns the string value of
   * the LASTMODIFIED property of the last document returned by nextDocument.
   * If the traversal <i>has</i> ended, it returns the finalCheckpoint string
   * passed to the constructor.
   */
  public String checkpoint() throws RepositoryException {
    if (document != null) {
      return Value.getSingleValueString(document,
          SpiConstants.PROPNAME_LASTMODIFIED);
    } else {
      return finalCheckpoint;
    }
  }
}
